Campaign endpoints

These endpoints create, read, change and delete campaigns. The numbers a campaign calls are managed separately. See Target endpoints.

Create a campaign

This endpoint creates a campaign with no targets. Add the targets next, with Add targets or Import targets.

Endpoint

POST /api/v1/campaignDialer/campaigns

Body

Property	Type	Description
campaignName	string	Required. Name of the campaign. It must be unique in the account, and cannot be changed afterwards.
defaultBotName	string	UUID of the bot that handles a call when the target does not name one of its own. Default null, in which case every target must name a bot.
defaultBotDisplayName	string	Display name of that bot. Default null.
maxRetries	number	How many further attempts to make on a number that failed. Default 6.
adminState	string	Locked or Unlocked. Default Unlocked. A locked campaign stays in the list but places no calls.
detectionCapabilities	object	What to do when a call does not reach a person. See below.
schedulerSettings	object	When the campaign may call, and how fast. See below.

detectionCapabilities holds these properties:

Property	Type	Description
minWaitDurationForAnswer	number	Seconds to wait for an answer. Default 20.
machineDetection	string	What to do when a fax or an answering machine picks up. Default Disconnect.
answerMachineBeepTimeout	number	Seconds to wait for the answering machine's beep before the bot starts speaking anyway. Default 20.

machineDetection takes these values:

Value	What happens
Disabled	No detection. The call goes to the bot regardless of what answered.
Disconnect	Default. A fax or an answering machine ends the call, and the number is retried.
Notify Answer Machine	A fax ends the call. An answering machine is passed to the bot, which can leave a message.

schedulerSettings holds these properties:

Property	Type	Description
maxCps	number	Required. Maximum calls per second.
maxConcurrentCalls	number	Required. Maximum number of calls running at once.
timeZone	string	Required. Time zone the dates and times below are read in, such as America/New-York. See Get the supported time zones.
beginningDate	string	Required. Date the campaign starts, YYYY-MM-DD.
endingDate	string	Required. Date the campaign ends, YYYY-MM-DD.
daysOfWeek	array	Required. Days of the week the campaign runs on, such as ["Sunday", "Tuesday", "Thursday"], or ["Everyday"].
minDurationBetweenRetries	number	Minutes to leave between attempts on the same number. Default 60.
startLocalTime	string	Start of the daily calling window, HH:mm. Default 08:00.
stopLocalTime	string	End of the daily calling window, HH:mm. Default 19:45.

Request

POST /api/v1/campaignDialer/campaigns HTTP/1.1
Host: livehub.audiocodes.io
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {token}

{
  "campaignName": "Nike Air US2",
  "defaultBotName": "47597ebb-1791-47f5-9c0b-2d8801d8beea",
  "defaultBotDisplayName": "Nike Bot",
  "maxRetries": 3,
  "detectionCapabilities": {
    "minWaitDurationForAnswer": 20,
    "machineDetection": "Disconnect",
    "answerMachineBeepTimeout": 20
  },
  "schedulerSettings": {
    "minDurationBetweenRetries": 60,
    "maxCps": 1,
    "maxConcurrentCalls": 30,
    "timeZone": "America/New-York",
    "beginningDate": "2023-07-28",
    "endingDate": "2023-08-24",
    "daysOfWeek": [
      "Sunday",
      "Tuesday",
      "Thursday"
    ],
    "startLocalTime": "08:00",
    "stopLocalTime": "19:45"
  },
  "adminState": "Unlocked"
}

Response

201 Created — the ID of the new campaign and the URI to address it by.

{
  "campaignID": "540e84e0f29b42d4a713446633441115",
  "campaignURI": "/api/v1/campaignDialer/campaigns/540e84e0f29b42d4a713446633441115"
}

400 Bad Request — the campaign was not created. A duplicate name is the usual cause.

{
  "error": {
    "message": "Campaign creation failed. Duplicate field error on field(s): campaignName"
  }
}

List campaigns

This endpoint lists every campaign in the account, the same set counted by Get the status of all campaigns.

Endpoint

GET /api/v1/campaignDialer/campaigns

Query parameters

Filtering, sorting and pagination follow the campaign query conventions. The filterable fields are:

Parameter	Description	Example
campaignName	Campaigns whose name contains the value.	?campaignName=demo
campaignStatus	Campaigns in one status. See Get campaign and target status values.	?campaignStatus=Completed
target_progress	Campaigns at one level of target progress: Not Initiated (0%), In Progress or Completed (100%).	?target_progress=Not%20Initiated%20(0%)
beginningDate	Campaigns that started after this date, YYYY-MM-DD.	?beginningDate=2024-03-18
endingDate	Campaigns that ended before this date, YYYY-MM-DD.	?endingDate=2025-02-18

Sorting accepts campaignName or campaignStatus as sortCol.

Request

GET /api/v1/campaignDialer/campaigns?sortCol=campaignName&sortDir=asc&beginningDate=2024-03-18&page=1&limit=5 HTTP/1.1
Host: livehub.audiocodes.io
Authorization: Bearer {token}

Response

200 OK — the campaigns, each in the form returned by Get a campaign, alongside the pagination properties.

Get a campaign

This endpoint retrieves the configuration and current status of one campaign.

Endpoint

GET /api/v1/campaignDialer/campaigns/{campaignID}

Request

GET /api/v1/campaignDialer/campaigns/671e131f414a5fec9bced6e7 HTTP/1.1
Host: livehub.audiocodes.io
Authorization: Bearer {token}

Response

200 OK — the campaign as it was configured, plus a status object describing how far it has progressed.

{
  "campaignName": "Nike Air US2",
  "campaignID": "671e131f414a5fec9bced6e7",
  "detectionCapabilities": {
    "machineDetection": "Disconnect",
    "minWaitDurationForAnswer": 20,
    "answerMachineBeepTimeout": 20
  },
  "schedulerSettings": {
    "maxCps": 10,
    "maxConcurrentCalls": 10,
    "timeZone": "Asia/Jerusalem",
    "beginningDate": "2024-05-08",
    "endingDate": "2024-05-31",
    "daysOfWeek": [
      "Everyday"
    ],
    "minDurationBetweenRetries": 60,
    "startLocalTime": "12:00",
    "stopLocalTime": "19:45"
  },
  "accountId": "1e98aaef-bcd7-4c82-a572-6d9202d9cb7a",
  "accountName": "media-campaign-4",
  "defaultBotName": "47597ebb-1791-47f5-9c0b-2d8801d8beea",
  "defaultBotDisplayName": "campaign_bot1",
  "maxRetries": 6,
  "adminState": "Unlocked",
  "status": {
    "campaignStatus": "Completed",
    "timeTotalHours": 168,
    "timeProgressHours": 35,
    "targetsEnabled": 4,
    "targetsCompleted": 4,
    "targetsAnswered": 2,
    "targetsFailed": 2
  }
}

Update a campaign

This endpoint changes a campaign at any point in its life. Every property is optional: send only what you are changing. This is also how you lock and unlock a campaign, through adminState.

The properties are those of Create a campaign, with two exceptions: campaignName is fixed once the campaign exists, and the time zone is fixed once the campaign has enabled targets.

Endpoint

PUT /api/v1/campaignDialer/campaigns/{campaignID}

Request

PUT /api/v1/campaignDialer/campaigns/663cdfd490ebc67dfbed8899 HTTP/1.1
Host: livehub.audiocodes.io
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {token}

{
  "defaultBotDisplayName": "Nike Bot3",
  "adminState": "Locked"
}

Response

200 OK — the campaign was updated.

{
  "campaignID": "663cdfd490ebc67dfbed8899",
  "campaignURI": "/api/v1/campaignDialer/campaigns/663cdfd490ebc67dfbed8899"
}

400 Bad Request — no campaign with that ID.

Delete a campaign

This endpoint deletes the campaign and everything belonging to it: its targets, its configuration and its statistics. This is irreversible.

Endpoint

DELETE /api/v1/campaignDialer/campaigns/{campaignID}

Request

DELETE /api/v1/campaignDialer/campaigns/663cdfd490ebc67dfbed8899 HTTP/1.1
Host: livehub.audiocodes.io
Authorization: Bearer {token}

Response

Code	Meaning
200 OK	The campaign was deleted.
400 Bad Request	No campaign with that ID.
500 Internal Server Error	Server error, or the campaign was already deleted.